

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>Appendix &mdash; Singularity container 3.5 documentation</title>
  

  
  
    <link rel="shortcut icon" href="_static/favicon.png"/>
  
  
  

  
  <script type="text/javascript" src="_static/js/modernizr.min.js"></script>
  
    
      <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
        <script src="_static/jquery.js"></script>
        <script src="_static/underscore.js"></script>
        <script src="_static/doctools.js"></script>
        <script src="_static/language_data.js"></script>
        <script src="_static/js/ga.js"></script>
    
    <script type="text/javascript" src="_static/js/theme.js"></script>

    

  
  <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
  <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
  <link rel="stylesheet" href="_static/css/custom.css" type="text/css" />
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Command Line Interface" href="cli.html" />
    <link rel="prev" title="Contributing" href="contributing.html" /> 
</head>

<body class="wy-body-for-nav">

   
  <div class="wy-grid-for-nav">
    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >
          

          
            <a href="index.html" class="icon icon-home"> Singularity container
          

          
            
            <img src="_static/logo.png" class="logo" alt="Logo"/>
          
          </a>

          
            
            
              <div class="version">
                3.5
              </div>
            
          

          
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

          
        </div>

        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
              
            
            
              <ul>
<li class="toctree-l1"><a class="reference internal" href="introduction.html">介绍</a></li>
<li class="toctree-l1"><a class="reference internal" href="quick_start.html">快速入门</a></li>
<li class="toctree-l1"><a class="reference internal" href="security.html">Singularity安全</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="build_a_container.html">Build容器</a></li>
<li class="toctree-l1"><a class="reference internal" href="definition_files.html">Definition文件</a></li>
<li class="toctree-l1"><a class="reference internal" href="build_env.html">Build环境</a></li>
<li class="toctree-l1"><a class="reference internal" href="singularity_and_docker.html">Singularity和Docker</a></li>
<li class="toctree-l1"><a class="reference internal" href="fakeroot.html">Fakeroot</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="signNverify.html">签名和认证</a></li>
<li class="toctree-l1"><a class="reference internal" href="key_commands.html">Key管理</a></li>
<li class="toctree-l1"><a class="reference internal" href="encryption.html">容器加密</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="endpoint.html">容器仓库</a></li>
<li class="toctree-l1"><a class="reference internal" href="cloud_library.html">Cloud Library</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="bind_paths_and_mounts.html">路径映射</a></li>
<li class="toctree-l1"><a class="reference internal" href="persistent_overlays.html">持久化Overlay</a></li>
<li class="toctree-l1"><a class="reference internal" href="running_services.html">运行服务</a></li>
<li class="toctree-l1"><a class="reference internal" href="environment_and_metadata.html">环境变量和元数据</a></li>
<li class="toctree-l1"><a class="reference internal" href="oci_runtime.html">OCI运行时</a></li>
<li class="toctree-l1"><a class="reference internal" href="plugins.html">插件</a></li>
<li class="toctree-l1"><a class="reference internal" href="security_options.html">安全选项</a></li>
<li class="toctree-l1"><a class="reference internal" href="networking.html">网络选项</a></li>
<li class="toctree-l1"><a class="reference internal" href="cgroups.html">Cgroups</a></li>
<li class="toctree-l1"><a class="reference internal" href="mpi.html">MPI应用</a></li>
<li class="toctree-l1"><a class="reference internal" href="gpu.html">GPU支持</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="contributing.html">Contributing</a></li>
</ul>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">Appendix</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#singularity-s-environment-variables">Singularity’s environment variables</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#a"><code class="docutils literal notranslate"><span class="pre">A</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#b"><code class="docutils literal notranslate"><span class="pre">B</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#c"><code class="docutils literal notranslate"><span class="pre">C</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#d"><code class="docutils literal notranslate"><span class="pre">D</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#e"><code class="docutils literal notranslate"><span class="pre">E</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#f"><code class="docutils literal notranslate"><span class="pre">F</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#g"><code class="docutils literal notranslate"><span class="pre">G</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#h"><code class="docutils literal notranslate"><span class="pre">H</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#i"><code class="docutils literal notranslate"><span class="pre">I</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#j"><code class="docutils literal notranslate"><span class="pre">J</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#k"><code class="docutils literal notranslate"><span class="pre">K</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#l"><code class="docutils literal notranslate"><span class="pre">L</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#n"><code class="docutils literal notranslate"><span class="pre">N</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#o"><code class="docutils literal notranslate"><span class="pre">O</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#p"><code class="docutils literal notranslate"><span class="pre">P</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#r"><code class="docutils literal notranslate"><span class="pre">R</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#s"><code class="docutils literal notranslate"><span class="pre">S</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#t"><code class="docutils literal notranslate"><span class="pre">T</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#u"><code class="docutils literal notranslate"><span class="pre">U</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#w"><code class="docutils literal notranslate"><span class="pre">W</span></code></a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#build-modules">Build Modules</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#library-bootstrap-agent"><code class="docutils literal notranslate"><span class="pre">library</span></code> bootstrap agent</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#overview">Overview</a></li>
<li class="toctree-l4"><a class="reference internal" href="#keywords">Keywords</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#docker-bootstrap-agent"><code class="docutils literal notranslate"><span class="pre">docker</span></code> bootstrap agent</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#sec-build-docker-module">Overview</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id3">Keywords</a></li>
<li class="toctree-l4"><a class="reference internal" href="#notes">Notes</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#shub-bootstrap-agent"><code class="docutils literal notranslate"><span class="pre">shub</span></code> bootstrap agent</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#id4">Overview</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id5">Keywords</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id6">Notes</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#oras-bootstrap-agent"><code class="docutils literal notranslate"><span class="pre">oras</span></code> bootstrap agent</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#id7">Overview</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id8">Keywords</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#localimage-bootstrap-agent"><code class="docutils literal notranslate"><span class="pre">localimage</span></code> bootstrap agent</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#id9">Overview</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id10">Keywords</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id11">Notes</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#yum-bootstrap-agent"><code class="docutils literal notranslate"><span class="pre">yum</span></code> bootstrap agent</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#id12">Overview</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id13">Keywords</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id14">Notes</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#debootstrap-build-agent"><code class="docutils literal notranslate"><span class="pre">debootstrap</span></code> build agent</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#id15">Overview</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id16">Keywords</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id17">Notes</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#arch-bootstrap-agent"><code class="docutils literal notranslate"><span class="pre">arch</span></code> bootstrap agent</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#id18">Overview</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id19">Keywords</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id20">Notes</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#busybox-bootstrap-agent"><code class="docutils literal notranslate"><span class="pre">busybox</span></code> bootstrap agent</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#id21">Overview</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id22">Keywords</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id23">Notes</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#zypper-bootstrap-agent"><code class="docutils literal notranslate"><span class="pre">zypper</span></code> bootstrap agent</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#id24">Overview</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id25">Keywords</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#docker-daemon-and-docker-archive-bootstrap-agents"><code class="docutils literal notranslate"><span class="pre">docker-daemon</span></code> and <code class="docutils literal notranslate"><span class="pre">docker-archive</span></code> bootstrap agents</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#id26">Overview</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id27">Keywords</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#scratch-bootstrap-agent"><code class="docutils literal notranslate"><span class="pre">scratch</span></code> bootstrap agent</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#id28">Overview</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id29">Keywords</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="cli.html">Command Line Reference</a></li>
</ul>

            
          
        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" aria-label="top navigation">
        
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="index.html">Singularity container</a>
        
      </nav>


      <div class="wy-nav-content">
        
        <div class="rst-content style-external-links">
        
          















<div role="navigation" aria-label="breadcrumbs navigation">

  <ul class="wy-breadcrumbs">
    
      <li><a href="index.html">Docs</a> &raquo;</li>
        
      <li>Appendix</li>
    
    
      <li class="wy-breadcrumbs-aside">
        
            
            
              <a href="https://github.com/sylabs/singularity-userdocs/blob/master/appendix.rst" class="fa fa-github"> Edit on GitHub</a>
            
          
        
      </li>
    
  </ul>

  
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
  <div class="section" id="appendix">
<span id="id1"></span><h1>Appendix<a class="headerlink" href="#appendix" title="Permalink to this headline">¶</a></h1>
<div class="section" id="singularity-s-environment-variables">
<span id="singularity-environment-variables"></span><h2>Singularity’s environment variables<a class="headerlink" href="#singularity-s-environment-variables" title="Permalink to this headline">¶</a></h2>
<p>Singularity 3.0 comes with some environment variables you can set or modify depending on your needs.
You can see them listed alphabetically below with their respective functionality.</p>
<div class="section" id="a">
<h3><code class="docutils literal notranslate"><span class="pre">A</span></code><a class="headerlink" href="#a" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li><p><strong>SINGULARITY_ADD_CAPS</strong>: To specify a list (comma separated string) of capabilities to be added. Default is an empty string.</p></li>
<li><p><strong>SINGULARITY_ALL</strong>: List all the users and groups capabilities.</p></li>
<li><p><strong>SINGULARITY_ALLOW_SETUID</strong>: To specify that setuid binaries should or not be allowed in the container. (root only) Default is set to false.</p></li>
<li><p><strong>SINGULARITY_APP</strong> and <strong>SINGULARITY_APPNAME</strong>: Sets the name of an application to be run inside a container.</p></li>
<li><p><strong>SINGULARITY_APPLY_CGROUPS</strong>: Used to apply cgroups from an input file for container processes. (it requires root privileges)</p></li>
</ol>
</div>
<div class="section" id="b">
<h3><code class="docutils literal notranslate"><span class="pre">B</span></code><a class="headerlink" href="#b" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li><p><strong>SINGULARITY_BINDPATH</strong> and <strong>SINGULARITY_BIND</strong>: Comma separated string <code class="docutils literal notranslate"><span class="pre">source:&lt;dest&gt;</span></code> list of paths to bind between the host and the container.</p></li>
<li><p><strong>SINGULARITY_BOOT</strong>: Set to false by default, considers if executing <code class="docutils literal notranslate"><span class="pre">/sbin/init</span></code> when container boots (root only).</p></li>
<li><p><strong>SINGULARITY_BUILDER</strong>: To specify the remote builder service URL. Defaults to our remote builder.</p></li>
</ol>
</div>
<div class="section" id="c">
<h3><code class="docutils literal notranslate"><span class="pre">C</span></code><a class="headerlink" href="#c" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li><p><strong>SINGULARITY_CACHEDIR</strong>: Specifies the directory for image downloads to be cached in.</p></li>
<li><p><strong>SINGULARITY_CLEANENV</strong>: Specifies if the environment should be cleaned or not before running the container. Default is set to false.</p></li>
<li><p><strong>SINGULARITY_CONTAIN</strong>: To use minimal <code class="docutils literal notranslate"><span class="pre">/dev</span></code> and empty other directories (e.g. <code class="docutils literal notranslate"><span class="pre">/tmp</span></code> and <code class="docutils literal notranslate"><span class="pre">$HOME</span></code>) instead of sharing filesystems from your host. Default is set to false.</p></li>
<li><p><strong>SINGULARITY_CONTAINALL</strong>: To contain not only file systems, but also PID, IPC, and environment. Default is set to false.</p></li>
<li><p><strong>SINGULARITY_CONTAINLIBS</strong>: Used to specify a string of file names (comma separated string) to bind to the <code class="docutils literal notranslate"><span class="pre">/.singularity.d/libs</span></code> directory.</p></li>
</ol>
</div>
<div class="section" id="d">
<h3><code class="docutils literal notranslate"><span class="pre">D</span></code><a class="headerlink" href="#d" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li><p><strong>SINGULARITY_DEFFILE</strong>: Shows the Singularity recipe that was used to generate the image.</p></li>
<li><p><strong>SINGULARITY_DESC</strong>: Contains a description of the capabilities.</p></li>
<li><p><strong>SINGULARITY_DETACHED</strong>: To submit a build job and print the build ID (no real-time logs and also requires <code class="docutils literal notranslate"><span class="pre">--remote</span></code>). Default is set to false.</p></li>
<li><p><strong>SINGULARITY_DISABLE_CACHE</strong>: To disable all caching of docker/oci, library, oras, etc. downloads and built SIFs. Default is set to false.</p></li>
<li><p><strong>SINGULARITY_DNS</strong>: A list of the DNS server addresses separated by commas to be added in <code class="docutils literal notranslate"><span class="pre">resolv.conf</span></code>.</p></li>
<li><p><strong>SINGULARITY_DOCKER_LOGIN</strong>: To specify the interactive prompt for docker authentication.</p></li>
<li><p><strong>SINGULARITY_DOCKER_USERNAME</strong>: To specify a username for docker authentication.</p></li>
<li><p><strong>SINGULARITY_DOCKER_PASSWORD</strong>: To specify the password for docker authentication.</p></li>
<li><p><strong>SINGULARITY_DROP_CAPS</strong>: To specify a list (comma separated string) of capabilities to be dropped. Default is an empty string.</p></li>
</ol>
</div>
<div class="section" id="e">
<h3><code class="docutils literal notranslate"><span class="pre">E</span></code><a class="headerlink" href="#e" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li><p><strong>SINGULARITY_ENVIRONMENT</strong>: Contains all the environment variables that have been exported in your container.</p></li>
<li><p><strong>SINGULARITY_ENCRYPTION_PASSPHRASE</strong>: Used to specify the plaintext passphrase to encrypt the container.</p></li>
<li><p><strong>SINGULARITY_ENCRYPTION_PEM_PATH</strong>: Used to specify the path of the file containing public or private key to encrypt the container in PEM format.</p></li>
<li><p><strong>SINGULARITYENV_*</strong>: Allows you to transpose variables into the container at runtime. You can see more in detail how to use this variable in our <a class="reference internal" href="environment_and_metadata.html#environment-and-metadata"><span class="std std-ref">environment and metadata section</span></a>.</p></li>
<li><p><strong>SINGULARITYENV_APPEND_PATH</strong>: Used to append directories to the end of the <code class="docutils literal notranslate"><span class="pre">$PATH</span></code> environment variable. You can see more in detail on how to use this variable in our <a class="reference internal" href="environment_and_metadata.html#environment-and-metadata"><span class="std std-ref">environment and metadata section</span></a>.</p></li>
<li><p><strong>SINGULARITYENV_PATH</strong>: A specified path to override the <code class="docutils literal notranslate"><span class="pre">$PATH</span></code> environment variable within the container. You can see more in detail on how to use this variable in our <a class="reference internal" href="environment_and_metadata.html#environment-and-metadata"><span class="std std-ref">environment and metadata section</span></a>.</p></li>
<li><p><strong>SINGULARITYENV_PREPEND_PATH</strong>: Used to prepend directories to the beginning of <cite>$PATH`</cite> environment variable. You can see more in detail on how to use this variable in our <a class="reference internal" href="environment_and_metadata.html#environment-and-metadata"><span class="std std-ref">environment and metadata section</span></a>.</p></li>
</ol>
</div>
<div class="section" id="f">
<h3><code class="docutils literal notranslate"><span class="pre">F</span></code><a class="headerlink" href="#f" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li><p><strong>SINGULARITY_FAKEROOT</strong>: Set to false by default, considers running the container in a new user namespace as uid 0 (experimental).</p></li>
<li><p><strong>SINGULARITY_FORCE</strong>: Forces to kill the instance.</p></li>
</ol>
</div>
<div class="section" id="g">
<h3><code class="docutils literal notranslate"><span class="pre">G</span></code><a class="headerlink" href="#g" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li><p><strong>SINGULARITY_GROUP</strong>: Used to specify a string of capabilities for the given group.</p></li>
</ol>
</div>
<div class="section" id="h">
<h3><code class="docutils literal notranslate"><span class="pre">H</span></code><a class="headerlink" href="#h" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li><p><strong>SINGULARITY_HELPFILE</strong>: Specifies the runscript helpfile, if it exists.</p></li>
<li><p><strong>SINGULARITY_HOME</strong> : A home directory specification, it could be a source or destination path. The source path is the home directory outside the container and the destination overrides the home directory within the container.</p></li>
<li><p><strong>SINGULARITY_HOSTNAME</strong>: The container’s hostname.</p></li>
</ol>
</div>
<div class="section" id="i">
<h3><code class="docutils literal notranslate"><span class="pre">I</span></code><a class="headerlink" href="#i" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li><p><strong>SINGULARITY_IMAGE</strong>: Filename of the container.</p></li>
</ol>
</div>
<div class="section" id="j">
<h3><code class="docutils literal notranslate"><span class="pre">J</span></code><a class="headerlink" href="#j" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li><p><strong>SINGULARITY_JSON</strong>: Specifies the structured json of the def file, every node as each section in the def file.</p></li>
</ol>
</div>
<div class="section" id="k">
<h3><code class="docutils literal notranslate"><span class="pre">K</span></code><a class="headerlink" href="#k" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li><p><strong>SINGULARITY_KEEP_PRIVS</strong>: To let root user keep privileges in the container. Default is set to false.</p></li>
</ol>
</div>
<div class="section" id="l">
<h3><code class="docutils literal notranslate"><span class="pre">L</span></code><a class="headerlink" href="#l" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li><p><strong>SINGULARITY_LABELS</strong>: Specifies the labels associated with the image.</p></li>
<li><p><strong>SINGULARITY_LIBRARY</strong>: Specifies the library to pull from. Default is set to our Cloud Library.</p></li>
</ol>
</div>
<div class="section" id="n">
<h3><code class="docutils literal notranslate"><span class="pre">N</span></code><a class="headerlink" href="#n" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li><p><strong>SINGULARITY_NAME</strong>: Specifies a custom image name.</p></li>
<li><p><strong>SINGULARITY_NETWORK</strong>: Used to specify a desired network. If more than one parameters is used, addresses should be separated by commas, where each network will bring up a dedicated interface inside the container.</p></li>
<li><p><strong>SINGULARITY_NETWORK_ARGS</strong>: To specify the network arguments to pass to CNI plugins.</p></li>
<li><p><strong>SINGULARITY_NOCLEANUP</strong>: To not clean up the bundle after a failed build, this can be helpful for debugging. Default is set to false.</p></li>
<li><p><strong>SINGULARITY_NOHTTPS</strong>: Sets to either false or true to avoid using HTTPS for communicating with the local docker registry. Default is set to false.</p></li>
<li><p><strong>SINGULARITY_NO_HOME</strong>: Considers not mounting users home directory if home is not the current working directory. Default is set to false.</p></li>
<li><p><strong>SINGULARITY_NO_INIT</strong> and <strong>SINGULARITY_NOSHIMINIT</strong>: Considers not starting the <code class="docutils literal notranslate"><span class="pre">shim</span></code> process with <code class="docutils literal notranslate"><span class="pre">--pid</span></code>.</p></li>
<li><p><strong>SINGULARITY_NO_NV</strong>: Flag to disable Nvidia support. Opposite of <code class="docutils literal notranslate"><span class="pre">SINGULARITY_NV</span></code>.</p></li>
<li><p><strong>SINGULARITY_NO_PRIVS</strong>: To drop all the privileges from root user in the container. Default is set to false.</p></li>
<li><p><strong>SINGULARITY_NV</strong>: To enable experimental Nvidia support. Default is set to false.</p></li>
</ol>
</div>
<div class="section" id="o">
<h3><code class="docutils literal notranslate"><span class="pre">O</span></code><a class="headerlink" href="#o" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li><p><strong>SINGULARITY_OVERLAY</strong> and <strong>SINGULARITY_OVERLAYIMAGE</strong>: To indicate the use of an overlay file system image for persistent data storage or as read-only layer of container.</p></li>
</ol>
</div>
<div class="section" id="p">
<h3><code class="docutils literal notranslate"><span class="pre">P</span></code><a class="headerlink" href="#p" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li><p><strong>SINGULARITY_PWD</strong> and <strong>SINGULARITY_TARGET_PWD</strong>: The initial working directory for payload process inside the container.</p></li>
</ol>
</div>
<div class="section" id="r">
<h3><code class="docutils literal notranslate"><span class="pre">R</span></code><a class="headerlink" href="#r" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li><p><strong>SINGULARITY_REMOTE</strong>: To build an image remotely. (Does not require root) Default is set to false.</p></li>
<li><p><strong>SINGULARITY_ROOTFS</strong>: To reference the system file location.</p></li>
<li><p><strong>SINGULARITY_RUNSCRIPT</strong>: Specifies the runscript of the image.</p></li>
</ol>
</div>
<div class="section" id="s">
<h3><code class="docutils literal notranslate"><span class="pre">S</span></code><a class="headerlink" href="#s" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li><p><strong>SINGULARITY_SANDBOX</strong>: To specify that the format of the image should be a sandbox. Default is set to false.</p></li>
<li><p><strong>SINGULARITY_SCRATCH</strong> and <strong>SINGULARITY_SCRATCHDIR</strong>: Used to include a scratch directory within the container that is linked to a temporary directory. (use -W to force location)</p></li>
<li><p><strong>SINGULARITY_SECTION</strong>: To specify a comma separated string of all the sections to be run from the deffile (setup, post, files, environment, test, labels, none)</p></li>
<li><p><strong>SINGULARITY_SECURITY</strong>: Used to enable security features. (SELinux, Apparmor, Seccomp)</p></li>
<li><p><strong>SINGULARITY_SECRET</strong>: Lists all the private keys instead of the default which display the public ones.</p></li>
<li><p><strong>SINGULARITY_SHELL</strong>: The path to the program to be used as an interactive shell.</p></li>
<li><p><strong>SINGULARITY_SIGNAL</strong>: Specifies a signal sent to the instance.</p></li>
</ol>
</div>
<div class="section" id="t">
<h3><code class="docutils literal notranslate"><span class="pre">T</span></code><a class="headerlink" href="#t" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li><p><strong>SINGULARITY_TEST</strong>: Specifies the test script for the image.</p></li>
<li><p><strong>SINGULARITY_TMPDIR</strong>: Used with the <code class="docutils literal notranslate"><span class="pre">build</span></code> command, to consider a temporary location for the build.</p></li>
</ol>
</div>
<div class="section" id="u">
<h3><code class="docutils literal notranslate"><span class="pre">U</span></code><a class="headerlink" href="#u" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li><p><strong>SINGULARITY_UNSHARE_PID</strong>: To specify that the container will run in a new PID namespace. Default is set to false.</p></li>
<li><p><strong>SINGULARITY_UNSHARE_IPC</strong>: To specify that the container will run in a new IPC namespace. Default is set to false.</p></li>
<li><p><strong>SINGULARITY_UNSHARE_NET</strong>: To specify that the container will run in a new network namespace (sets up a bridge network interface by default). Default is set to false.</p></li>
<li><p><strong>SINGULARITY_UNSHARE_UTS</strong>: To specify that the container will run in a new UTS namespace. Default is set to false.</p></li>
<li><p><strong>SINGULARITY_UPDATE</strong>: To run the definition over an existing container (skips the header). Default is set to false.</p></li>
<li><p><strong>SINGULARITY_URL</strong>: Specifies the key server <code class="docutils literal notranslate"><span class="pre">URL</span></code>.</p></li>
<li><p><strong>SINGULARITY_USER</strong>: Used to specify a string of capabilities for the given user.</p></li>
<li><p><strong>SINGULARITY_USERNS</strong> and <strong>SINGULARITY_UNSHARE_USERNS</strong>: To specify that the container will run in a new user namespace, allowing Singularity to run completely unprivileged on recent kernels. This may not support every feature of Singularity. (Sandbox image only). Default is set to false.</p></li>
</ol>
</div>
<div class="section" id="w">
<h3><code class="docutils literal notranslate"><span class="pre">W</span></code><a class="headerlink" href="#w" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li><p><strong>SINGULARITY_WORKDIR</strong>: The working directory to be used for <code class="docutils literal notranslate"><span class="pre">/tmp</span></code>, <code class="docutils literal notranslate"><span class="pre">/var/tmp</span></code> and <code class="docutils literal notranslate"><span class="pre">$HOME</span></code> (if <code class="docutils literal notranslate"><span class="pre">-c</span></code> or <code class="docutils literal notranslate"><span class="pre">--contain</span></code> was also used)</p></li>
<li><p><strong>SINGULARITY_WRITABLE</strong>: By default, all Singularity containers are available as read only, this option makes the file system accessible as read/write. Default set to false.</p></li>
<li><p><strong>SINGULARITY_WRITABLE_TMPFS</strong>: Makes the file system accessible as read-write with non-persistent data (with overlay support only). Default is set to false.</p></li>
</ol>
</div>
</div>
<div class="section" id="build-modules">
<span id="buildmodules"></span><h2>Build Modules<a class="headerlink" href="#build-modules" title="Permalink to this headline">¶</a></h2>
<div class="section" id="library-bootstrap-agent">
<span id="build-library-module"></span><h3><code class="docutils literal notranslate"><span class="pre">library</span></code> bootstrap agent<a class="headerlink" href="#library-bootstrap-agent" title="Permalink to this headline">¶</a></h3>
<div class="section" id="overview">
<span id="sec-build-library-module"></span><h4>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h4>
<p>You can use an existing container on the Container Library as your “base,” and
then add customization. This allows you to build multiple images from the same
starting point. For example, you may want to build several containers with the
same custom python installation, the same custom compiler toolchain, or the same
base MPI installation. Instead of building these from scratch each time, you
could create a base container on the Container Library and then build new
containers from that existing base container adding customizations in <code class="docutils literal notranslate"><span class="pre">%post</span></code>,
<code class="docutils literal notranslate"><span class="pre">%environment</span></code>, <code class="docutils literal notranslate"><span class="pre">%runscript</span></code>, etc.</p>
</div>
<div class="section" id="keywords">
<h4>Keywords<a class="headerlink" href="#keywords" title="Permalink to this headline">¶</a></h4>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">Bootstrap</span>: library
</pre></div>
</div>
<p>The Bootstrap keyword is always mandatory. It describes the bootstrap module to
use.</p>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">From</span>: &lt;entity&gt;/&lt;collection&gt;/&lt;container&gt;:&lt;tag&gt;
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">From</span></code> keyword is mandatory. It specifies the container to use as a base.
<code class="docutils literal notranslate"><span class="pre">entity</span></code> is optional and defaults to <code class="docutils literal notranslate"><span class="pre">library</span></code>. <code class="docutils literal notranslate"><span class="pre">collection</span></code> is
optional and defaults to <code class="docutils literal notranslate"><span class="pre">default</span></code>. This is the correct namespace to use for
some official containers (<code class="docutils literal notranslate"><span class="pre">alpine</span></code> for example). <code class="docutils literal notranslate"><span class="pre">tag</span></code> is also optional and
will default to <code class="docutils literal notranslate"><span class="pre">latest</span></code>.</p>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span>Library: http://custom/library
</pre></div>
</div>
<p>The Library keyword is optional. It will default to
<code class="docutils literal notranslate"><span class="pre">https://library.sylabs.io</span></code>.</p>
</div>
</div>
<div class="section" id="docker-bootstrap-agent">
<span id="build-docker-module"></span><h3><code class="docutils literal notranslate"><span class="pre">docker</span></code> bootstrap agent<a class="headerlink" href="#docker-bootstrap-agent" title="Permalink to this headline">¶</a></h3>
<div class="section" id="sec-build-docker-module">
<span id="id2"></span><h4>Overview<a class="headerlink" href="#sec-build-docker-module" title="Permalink to this headline">¶</a></h4>
<p>Docker images are comprised of layers that are assembled at runtime to create an
image. You can use Docker layers to create a base image, and then add your own
custom software. For example, you might use Docker’s Ubuntu image layers to
create an Ubuntu Singularity container. You could do the same with CentOS,
Debian, Arch, Suse, Alpine, BusyBox, etc.</p>
<p>Or maybe you want a container that already has software installed. For instance,
maybe you want to build a container that uses CUDA and cuDNN to leverage the
GPU, but you don’t want to install from scratch. You can start with one of the
<code class="docutils literal notranslate"><span class="pre">nvidia/cuda</span></code> containers and install your software on top of that.</p>
<p>Or perhaps you have already invested in Docker and created your own Docker
containers. If so, you can seamlessly convert them to Singularity with the
<code class="docutils literal notranslate"><span class="pre">docker</span></code> bootstrap module.</p>
</div>
<div class="section" id="id3">
<h4>Keywords<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h4>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">Bootstrap</span>: docker
</pre></div>
</div>
<p>The Bootstrap keyword is always mandatory. It describes the bootstrap module to
use.</p>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">From</span>: &lt;registry&gt;/&lt;namespace&gt;/&lt;container&gt;:&lt;tag&gt;@&lt;digest&gt;
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">From</span></code> keyword is mandatory. It specifies the container to use as a base.
<code class="docutils literal notranslate"><span class="pre">registry</span></code> is optional and defaults to <code class="docutils literal notranslate"><span class="pre">index.docker.io</span></code>. <code class="docutils literal notranslate"><span class="pre">namespace</span></code> is
optional and defaults to <code class="docutils literal notranslate"><span class="pre">library</span></code>. This is the correct namespace to use for
some official containers (ubuntu for example). <code class="docutils literal notranslate"><span class="pre">tag</span></code> is also optional and will
default to <code class="docutils literal notranslate"><span class="pre">latest</span></code></p>
<p>See <a class="reference internal" href="singularity_and_docker.html#singularity-and-docker"><span class="std std-ref">Singularity and Docker</span></a> for more detailed
info on using Docker registries.</p>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">Registry</span>: http://custom_registry
</pre></div>
</div>
<p>The Registry keyword is optional. It will default to <code class="docutils literal notranslate"><span class="pre">index.docker.io</span></code>.</p>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">Namespace</span>: namespace
</pre></div>
</div>
<p>The Namespace keyword is optional. It will default to <code class="docutils literal notranslate"><span class="pre">library</span></code>.</p>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">IncludeCmd</span>: yes
</pre></div>
</div>
<p>The IncludeCmd keyword is optional. If included, and if a <code class="docutils literal notranslate"><span class="pre">%runscript</span></code> is not
specified, a Docker <code class="docutils literal notranslate"><span class="pre">CMD</span></code> will take precedence over <code class="docutils literal notranslate"><span class="pre">ENTRYPOINT</span></code> and will be
used as a runscript. Note that the <code class="docutils literal notranslate"><span class="pre">IncludeCmd</span></code> keyword is considered valid if
it is not empty! This means that <code class="docutils literal notranslate"><span class="pre">IncludeCmd:</span> <span class="pre">yes</span></code> and <code class="docutils literal notranslate"><span class="pre">IncludeCmd:</span> <span class="pre">no</span></code> are
identical. In both cases the <code class="docutils literal notranslate"><span class="pre">IncludeCmd</span></code> keyword is not empty, so the Docker
<code class="docutils literal notranslate"><span class="pre">CMD</span></code> will take precedence over an <code class="docutils literal notranslate"><span class="pre">ENTRYPOINT</span></code>.</p>
<blockquote>
<div><p>See <a class="reference internal" href="singularity_and_docker.html#singularity-and-docker"><span class="std std-ref">Singularity and Docker</span></a> for more info on
order of operations for determining a runscript.</p>
</div></blockquote>
</div>
<div class="section" id="notes">
<h4>Notes<a class="headerlink" href="#notes" title="Permalink to this headline">¶</a></h4>
<p>Docker containers are stored as a collection of tarballs called layers. When
building from a Docker container the layers must be downloaded and then
assembled in the proper order to produce a viable file system. Then the file
system must be converted to Singularity Image File (sif) format.</p>
<p>Building from Docker Hub is not considered reproducible because if any of the
layers of the image are changed, the container will change. If reproducibility
is important to your workflow, consider hosting a base container on the
Container Library and building from it instead.</p>
<p>For detailed information about setting your build environment see
<a class="reference internal" href="build_env.html#build-environment"><span class="std std-ref">Build Customization</span></a>.</p>
</div>
</div>
<div class="section" id="shub-bootstrap-agent">
<span id="build-shub"></span><h3><code class="docutils literal notranslate"><span class="pre">shub</span></code> bootstrap agent<a class="headerlink" href="#shub-bootstrap-agent" title="Permalink to this headline">¶</a></h3>
<div class="section" id="id4">
<h4>Overview<a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h4>
<p>You can use an existing container on Singularity Hub as your “base,” and then
add customization. This allows you to build multiple images from the same
starting point. For example, you may want to build several containers with the
same custom python installation, the same custom compiler toolchain, or the same
base MPI installation. Instead of building these from scratch each time, you
could create a base container on Singularity Hub and then build new containers
from that existing base container adding customizations in <code class="docutils literal notranslate"><span class="pre">%post</span></code> ,
<code class="docutils literal notranslate"><span class="pre">%environment</span></code>, <code class="docutils literal notranslate"><span class="pre">%runscript</span></code>, etc.</p>
</div>
<div class="section" id="id5">
<h4>Keywords<a class="headerlink" href="#id5" title="Permalink to this headline">¶</a></h4>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">Bootstrap</span>: shub
</pre></div>
</div>
<p>The Bootstrap keyword is always mandatory. It describes the bootstrap module to
use.</p>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">From</span>: shub://&lt;registry&gt;/&lt;username&gt;/&lt;container-name&gt;:&lt;tag&gt;@digest
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">From</span></code> keyword is mandatory. It specifies the container to use as a base.
<code class="docutils literal notranslate"><span class="pre">registry</span> <span class="pre">is</span> <span class="pre">optional</span> <span class="pre">and</span> <span class="pre">defaults</span> <span class="pre">to</span> <span class="pre">``singularity-hub.org</span></code>. <code class="docutils literal notranslate"><span class="pre">tag</span></code> and
<code class="docutils literal notranslate"><span class="pre">digest</span></code> are also optional. <code class="docutils literal notranslate"><span class="pre">tag</span></code> defaults to <code class="docutils literal notranslate"><span class="pre">latest</span></code> and <code class="docutils literal notranslate"><span class="pre">digest</span></code> can
be left blank if you want the latest build.</p>
</div>
<div class="section" id="id6">
<h4>Notes<a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h4>
<p>When bootstrapping from a Singularity Hub image, all previous definition files
that led to the creation of the current image will be stored in a directory
within the container called <code class="docutils literal notranslate"><span class="pre">/.singularity.d/bootstrap_history</span></code>. Singularity
will also alert you if environment variables have been changed between the base
image and the new image during bootstrap.</p>
</div>
</div>
<div class="section" id="oras-bootstrap-agent">
<span id="build-oras"></span><h3><code class="docutils literal notranslate"><span class="pre">oras</span></code> bootstrap agent<a class="headerlink" href="#oras-bootstrap-agent" title="Permalink to this headline">¶</a></h3>
<div class="section" id="id7">
<h4>Overview<a class="headerlink" href="#id7" title="Permalink to this headline">¶</a></h4>
<p>Using, this module, a container from supporting OCI Registries - Eg: ACR (Azure Container
Registry), local container registries, etc can be used as your “base” image and later
customized. This allows you to build multiple images from the same starting point. For
example, you may want to build several containers with the same custom python installation,
the same custom compiler toolchain, or the same base MPI installation. Instead of
building these from scratch each time, you could make use of <code class="docutils literal notranslate"><span class="pre">oras</span></code> to pull an
appropriate base container and then build new containers by adding customizations in
<code class="docutils literal notranslate"><span class="pre">%post</span></code> , <code class="docutils literal notranslate"><span class="pre">%environment</span></code>, <code class="docutils literal notranslate"><span class="pre">%runscript</span></code>, etc.</p>
</div>
<div class="section" id="id8">
<h4>Keywords<a class="headerlink" href="#id8" title="Permalink to this headline">¶</a></h4>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">Bootstrap</span>: oras
</pre></div>
</div>
<p>The Bootstrap keyword is always mandatory. It describes the bootstrap module to
use.</p>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">From</span>: oras://registry/namespace/image:tag
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">From</span></code> keyword is mandatory. It specifies the container to use as a base.
Also,``tag`` is mandatory that refers to the version of image you want to use.</p>
</div>
</div>
<div class="section" id="localimage-bootstrap-agent">
<span id="build-localimage"></span><h3><code class="docutils literal notranslate"><span class="pre">localimage</span></code> bootstrap agent<a class="headerlink" href="#localimage-bootstrap-agent" title="Permalink to this headline">¶</a></h3>
<p id="sec-build-localimage">This module allows you to build a container from an existing Singularity
container on your host system. The name is somewhat misleading because your
container can be in either image or directory format.</p>
<div class="section" id="id9">
<h4>Overview<a class="headerlink" href="#id9" title="Permalink to this headline">¶</a></h4>
<p>You can use an existing container image as your “base”, and then add
customization. This allows you to build multiple images from the same starting
point. For example, you may want to build several containers with the same
custom python installation, the same custom compiler toolchain, or the same base
MPI installation. Instead of building these from scratch each time, you could
start with the appropriate local base container and then customize the new
container in <code class="docutils literal notranslate"><span class="pre">%post</span></code>, <code class="docutils literal notranslate"><span class="pre">%environment</span></code>, <code class="docutils literal notranslate"><span class="pre">%runscript</span></code>, etc.</p>
</div>
<div class="section" id="id10">
<h4>Keywords<a class="headerlink" href="#id10" title="Permalink to this headline">¶</a></h4>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">Bootstrap</span>: localimage
</pre></div>
</div>
<p>The Bootstrap keyword is always mandatory. It describes the bootstrap module to
use.</p>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">From</span>: /path/to/container/file/or/directory
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">From</span></code> keyword is mandatory. It specifies the local container to use as a
base.</p>
</div>
<div class="section" id="id11">
<h4>Notes<a class="headerlink" href="#id11" title="Permalink to this headline">¶</a></h4>
<p>When building from a local container, all previous definition files that led to
the creation of the current container will be stored in a directory within the
container called <code class="docutils literal notranslate"><span class="pre">/.singularity.d/bootstrap_history</span></code>. Singularity will also
alert you if environment variables have been changed between the base image and
the new image during bootstrap.</p>
</div>
</div>
<div class="section" id="yum-bootstrap-agent">
<span id="build-yum"></span><h3><code class="docutils literal notranslate"><span class="pre">yum</span></code> bootstrap agent<a class="headerlink" href="#yum-bootstrap-agent" title="Permalink to this headline">¶</a></h3>
<p id="sec-build-yum">This module allows you to build a Red Hat/CentOS/Scientific Linux style
container from a mirror URI.</p>
<div class="section" id="id12">
<h4>Overview<a class="headerlink" href="#id12" title="Permalink to this headline">¶</a></h4>
<p>Use the <code class="docutils literal notranslate"><span class="pre">yum</span></code> module to specify a base for a CentOS-like container. You must
also specify the URI for the mirror you would like to use.</p>
</div>
<div class="section" id="id13">
<h4>Keywords<a class="headerlink" href="#id13" title="Permalink to this headline">¶</a></h4>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">Bootstrap</span>: yum
</pre></div>
</div>
<p>The Bootstrap keyword is always mandatory. It describes the bootstrap module to
use.</p>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">OSVersion</span>: <span class="m">7</span>
</pre></div>
</div>
<p>The OSVersion keyword is optional. It specifies the OS version you would like to
use. It is only required if you have specified a %{OSVERSION} variable in the
<code class="docutils literal notranslate"><span class="pre">MirrorURL</span></code> keyword.</p>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">MirrorURL</span>: http://mirror.centos.org/centos-%{OSVERSION}/%{OSVERSION}/os/$basearch/
</pre></div>
</div>
<p>The MirrorURL keyword is mandatory. It specifies the URI to use as a mirror to
download the OS. If you define the <code class="docutils literal notranslate"><span class="pre">OSVersion</span></code> keyword, then you can use it in
the URI as in the example above.</p>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">Include</span>: yum
</pre></div>
</div>
<p>The Include keyword is optional. It allows you to install additional packages
into the core operating system. It is a best practice to supply only the bare
essentials such that the <code class="docutils literal notranslate"><span class="pre">%post</span></code> section has what it needs to properly
complete the build. One common package you may want to install when using the
<code class="docutils literal notranslate"><span class="pre">yum</span></code> build module is YUM itself.</p>
</div>
<div class="section" id="id14">
<h4>Notes<a class="headerlink" href="#id14" title="Permalink to this headline">¶</a></h4>
<p>There is a major limitation with using YUM to bootstrap a container. The RPM
database that exists within the container will be created using the RPM library
and Berkeley DB implementation that exists on the host system. If the RPM
implementation inside the container is not compatible with the RPM database that
was used to create the container, RPM and YUM commands inside the container may
fail. This issue can be easily demonstrated by bootstrapping an older RHEL
compatible image by a newer one (e.g. bootstrap a Centos 5 or 6 container from a
Centos 7 host).</p>
<p>In order to use the <code class="docutils literal notranslate"><span class="pre">yum</span></code> build module, you must have <code class="docutils literal notranslate"><span class="pre">yum</span></code>
installed on your system. It may seem counter-intuitive to install YUM on a
system that uses a different package manager, but you can do so. For instance,
on Ubuntu you can install it like so:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ sudo apt-get update &amp;&amp; sudo apt-get install yum
</pre></div>
</div>
</div>
</div>
<div class="section" id="debootstrap-build-agent">
<span id="build-debootstrap"></span><h3><code class="docutils literal notranslate"><span class="pre">debootstrap</span></code> build agent<a class="headerlink" href="#debootstrap-build-agent" title="Permalink to this headline">¶</a></h3>
<p id="sec-build-debootstrap">This module allows you to build a Debian/Ubuntu style container from a mirror
URI.</p>
<div class="section" id="id15">
<h4>Overview<a class="headerlink" href="#id15" title="Permalink to this headline">¶</a></h4>
<p>Use the <code class="docutils literal notranslate"><span class="pre">debootstrap</span></code> module to specify a base for a Debian-like container.
You must also specify the OS version and a URI for the mirror you would like to
use.</p>
</div>
<div class="section" id="id16">
<h4>Keywords<a class="headerlink" href="#id16" title="Permalink to this headline">¶</a></h4>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">Bootstrap</span>: debootstrap
</pre></div>
</div>
<p>The Bootstrap keyword is always mandatory. It describes the bootstrap module to
use.</p>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">OSVersion</span>: xenial
</pre></div>
</div>
<p>The OSVersion keyword is mandatory. It specifies the OS version you would like
to use. For Ubuntu you can use code words like <code class="docutils literal notranslate"><span class="pre">trusty</span></code> (14.04), <code class="docutils literal notranslate"><span class="pre">xenial</span></code>
(16.04), and <code class="docutils literal notranslate"><span class="pre">yakkety</span></code> (17.04). For Debian you can use values like <code class="docutils literal notranslate"><span class="pre">stable</span></code>,
<code class="docutils literal notranslate"><span class="pre">oldstable</span></code>, <code class="docutils literal notranslate"><span class="pre">testing</span></code>, and <code class="docutils literal notranslate"><span class="pre">unstable</span></code> or code words like <code class="docutils literal notranslate"><span class="pre">wheezy</span></code> (7),
<code class="docutils literal notranslate"><span class="pre">jesse</span></code> (8), and <code class="docutils literal notranslate"><span class="pre">stretch</span></code> (9).</p>
<blockquote>
<div><div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">MirrorURL</span>:  http://us.archive.ubuntu.com/ubuntu/
</pre></div>
</div>
</div></blockquote>
<p>The MirrorURL keyword is mandatory. It specifies a URI to use as a mirror when
downloading the OS.</p>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">Include</span>: somepackage
</pre></div>
</div>
<p>The Include keyword is optional. It allows you to install additional packages
into the core operating system. It is a best practice to supply only the bare
essentials such that the <code class="docutils literal notranslate"><span class="pre">%post</span></code> section has what it needs to properly
complete the build.</p>
</div>
<div class="section" id="id17">
<h4>Notes<a class="headerlink" href="#id17" title="Permalink to this headline">¶</a></h4>
<p>In order to use the <code class="docutils literal notranslate"><span class="pre">debootstrap</span></code> build module, you must have <code class="docutils literal notranslate"><span class="pre">debootstrap</span></code>
installed on your system. On Ubuntu you can install it like so:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ sudo apt-get update &amp;&amp; sudo apt-get install debootstrap
</pre></div>
</div>
<p>On CentOS you can install it from the epel repos like so:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ sudo yum update &amp;&amp; sudo yum install epel-release &amp;&amp; sudo yum install debootstrap.noarch
</pre></div>
</div>
</div>
</div>
<div class="section" id="arch-bootstrap-agent">
<span id="build-arch"></span><h3><code class="docutils literal notranslate"><span class="pre">arch</span></code> bootstrap agent<a class="headerlink" href="#arch-bootstrap-agent" title="Permalink to this headline">¶</a></h3>
<p id="sec-build-arch">This module allows you to build a Arch Linux based container.</p>
<div class="section" id="id18">
<h4>Overview<a class="headerlink" href="#id18" title="Permalink to this headline">¶</a></h4>
<p>Use the <code class="docutils literal notranslate"><span class="pre">arch</span></code> module to specify a base for an Arch Linux based container.
Arch Linux uses the aptly named <code class="docutils literal notranslate"><span class="pre">pacman</span></code> package manager (all puns intended).</p>
</div>
<div class="section" id="id19">
<h4>Keywords<a class="headerlink" href="#id19" title="Permalink to this headline">¶</a></h4>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">Bootstrap</span>: arch
</pre></div>
</div>
<p>The Bootstrap keyword is always mandatory. It describes the bootstrap module to
use.</p>
<p>The Arch Linux bootstrap module does not name any additional keywords at this
time. By defining the <code class="docutils literal notranslate"><span class="pre">arch</span></code> module, you have essentially given all of the
information necessary for that particular bootstrap module to build a core
operating system.</p>
</div>
<div class="section" id="id20">
<h4>Notes<a class="headerlink" href="#id20" title="Permalink to this headline">¶</a></h4>
<p>Arch Linux is, by design, a very stripped down, light-weight OS. You may need to
perform a significant amount of configuration to get a usable OS. Please refer
to this
<a class="reference external" href="https://github.com/singularityware/singularity/blob/master/examples/arch/README.md">README.md</a>
and the
<a class="reference external" href="https://github.com/singularityware/singularity/blob/master/examples/arch/Singularity">Arch Linux example</a>
for more info.</p>
</div>
</div>
<div class="section" id="busybox-bootstrap-agent">
<span id="build-busybox"></span><h3><code class="docutils literal notranslate"><span class="pre">busybox</span></code> bootstrap agent<a class="headerlink" href="#busybox-bootstrap-agent" title="Permalink to this headline">¶</a></h3>
<p id="sec-build-busybox">This module allows you to build a container based on BusyBox.</p>
<div class="section" id="id21">
<h4>Overview<a class="headerlink" href="#id21" title="Permalink to this headline">¶</a></h4>
<p>Use the <code class="docutils literal notranslate"><span class="pre">busybox</span></code> module to specify a BusyBox base for container. You must
also specify a URI for the mirror you would like to use.</p>
</div>
<div class="section" id="id22">
<h4>Keywords<a class="headerlink" href="#id22" title="Permalink to this headline">¶</a></h4>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">Bootstrap</span>: busybox
</pre></div>
</div>
<p>The Bootstrap keyword is always mandatory. It describes the bootstrap module to
use.</p>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">MirrorURL</span>: https://www.busybox.net/downloads/binaries/<span class="m">1.26.1</span>-defconfig-multiarch/busybox-x86_64
</pre></div>
</div>
<p>The MirrorURL keyword is mandatory. It specifies a URI to use as a mirror when
downloading the OS.</p>
</div>
<div class="section" id="id23">
<h4>Notes<a class="headerlink" href="#id23" title="Permalink to this headline">¶</a></h4>
<p>You can build a fully functional BusyBox container that only takes up ~600kB of
disk space!</p>
</div>
</div>
<div class="section" id="zypper-bootstrap-agent">
<span id="build-zypper"></span><h3><code class="docutils literal notranslate"><span class="pre">zypper</span></code> bootstrap agent<a class="headerlink" href="#zypper-bootstrap-agent" title="Permalink to this headline">¶</a></h3>
<p id="sec-build-zypper">This module allows you to build a Suse style container from a mirror URI.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p><code class="docutils literal notranslate"><span class="pre">zypper</span></code> version 1.11.20 or greater is required on the host system, as
Singularity requires the <code class="docutils literal notranslate"><span class="pre">--releasever</span></code> flag.</p>
</div>
<div class="section" id="id24">
<h4>Overview<a class="headerlink" href="#id24" title="Permalink to this headline">¶</a></h4>
<p>Use the <code class="docutils literal notranslate"><span class="pre">zypper</span></code> module to specify a base for a Suse-like container. You must
also specify a URI for the mirror you would like to use.</p>
</div>
<div class="section" id="id25">
<h4>Keywords<a class="headerlink" href="#id25" title="Permalink to this headline">¶</a></h4>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">Bootstrap</span>: zypper
</pre></div>
</div>
<p>The Bootstrap keyword is always mandatory. It describes the bootstrap module to
use.</p>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">OSVersion</span>: <span class="m">42.2</span>
</pre></div>
</div>
<p>The OSVersion keyword is optional. It specifies the OS version you would like to
use. It is only required if you have specified a %{OSVERSION} variable in the
<code class="docutils literal notranslate"><span class="pre">MirrorURL</span></code> keyword.</p>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">Include</span>: somepackage
</pre></div>
</div>
<p>The Include keyword is optional. It allows you to install additional packages
into the core operating system. It is a best practice to supply only the bare
essentials such that the <code class="docutils literal notranslate"><span class="pre">%post</span></code> section has what it needs to properly
complete the build. One common package you may want to install when using the
zypper build module is <code class="docutils literal notranslate"><span class="pre">zypper</span></code> itself.</p>
</div>
</div>
<div class="section" id="docker-daemon-and-docker-archive-bootstrap-agents">
<span id="docker-daemon-archive"></span><h3><code class="docutils literal notranslate"><span class="pre">docker-daemon</span></code> and <code class="docutils literal notranslate"><span class="pre">docker-archive</span></code> bootstrap agents<a class="headerlink" href="#docker-daemon-and-docker-archive-bootstrap-agents" title="Permalink to this headline">¶</a></h3>
<p>If you are using docker locally there are two options for creating Singularity
images without the need for a repository. You can either build a SIF from a
<code class="docutils literal notranslate"><span class="pre">docker-save</span></code> tar file or you can convert any docker image present in
docker’s daemon internal storage.</p>
<div class="section" id="id26">
<h4>Overview<a class="headerlink" href="#id26" title="Permalink to this headline">¶</a></h4>
<p><code class="docutils literal notranslate"><span class="pre">docker-daemon</span></code> allows you to build a SIF from any docker image currently
residing in docker’s daemon internal storage:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> docker images alpine
<span class="go">REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE</span>
<span class="go">alpine              latest              965ea09ff2eb        7 weeks ago         5.55MB</span>

<span class="gp">$</span> singularity run docker-daemon:alpine:latest
<span class="go">INFO:    Converting OCI blobs to SIF format</span>
<span class="go">INFO:    Starting build...</span>
<span class="go">Getting image source signatures</span>
<span class="go">Copying blob 77cae8ab23bf done</span>
<span class="go">Copying config 759e71f0d3 done</span>
<span class="go">Writing manifest to image destination</span>
<span class="go">Storing signatures</span>
<span class="go">2019/12/11 14:53:24  info unpack layer: sha256:eb7c47c7f0fd0054242f35366d166e6b041dfb0b89e5f93a82ad3a3206222502</span>
<span class="go">INFO:    Creating SIF file...</span>
<span class="go">Singularity&gt;</span>
</pre></div>
</div>
<p>while <code class="docutils literal notranslate"><span class="pre">docker-archive</span></code> permits you to do the same thing starting from a docker
image stored in a <code class="docutils literal notranslate"><span class="pre">docker-save</span></code> formatted tar file:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> docker save -o alpine.tar alpine:latest

<span class="gp">$</span> singularity run docker-archive:<span class="k">$(</span><span class="nb">pwd</span><span class="k">)</span>/alpine.tar
<span class="go">INFO:    Converting OCI blobs to SIF format</span>
<span class="go">INFO:    Starting build...</span>
<span class="go">Getting image source signatures</span>
<span class="go">Copying blob 77cae8ab23bf done</span>
<span class="go">Copying config 759e71f0d3 done</span>
<span class="go">Writing manifest to image destination</span>
<span class="go">Storing signatures</span>
<span class="go">2019/12/11 15:25:09  info unpack layer: sha256:eb7c47c7f0fd0054242f35366d166e6b041dfb0b89e5f93a82ad3a3206222502</span>
<span class="go">INFO:    Creating SIF file...</span>
<span class="go">Singularity&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="id27">
<h4>Keywords<a class="headerlink" href="#id27" title="Permalink to this headline">¶</a></h4>
<p>The <code class="docutils literal notranslate"><span class="pre">docker-daemon</span></code> bootstrap agent can be used in a Singularity definition file
as follows:</p>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">From</span>: docker-daemon:&lt;image&gt;:&lt;tag&gt;
</pre></div>
</div>
<p>where both <code class="docutils literal notranslate"><span class="pre">&lt;image&gt;</span></code> and <code class="docutils literal notranslate"><span class="pre">&lt;tag&gt;</span></code> are mandatory fields that must be written explicitly.
The <code class="docutils literal notranslate"><span class="pre">docker-archive</span></code> bootstrap agent requires instead the path to the tar file
containing the image:</p>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">From</span>: docker-archive:&lt;path-to-tar-file&gt;
</pre></div>
</div>
<p>Note that differently from the <code class="docutils literal notranslate"><span class="pre">docker://</span></code> bootstrap agent both <code class="docutils literal notranslate"><span class="pre">docker-daemon</span></code> and
<code class="docutils literal notranslate"><span class="pre">docker-archive</span></code> don’t require a double slash <code class="docutils literal notranslate"><span class="pre">//</span></code> after the colon in the agent name.</p>
</div>
</div>
<div class="section" id="scratch-bootstrap-agent">
<span id="scratch-agent"></span><h3><code class="docutils literal notranslate"><span class="pre">scratch</span></code> bootstrap agent<a class="headerlink" href="#scratch-bootstrap-agent" title="Permalink to this headline">¶</a></h3>
<p>Through all the Bootstrap agents mentioned above, you were essentially building
over a base(parent) image pulled from either Library/Docker/Shub/Oras etc, but
Singularity offers support to create even the base images or minimal images to
create your custom containers.</p>
<div class="section" id="id28">
<h4>Overview<a class="headerlink" href="#id28" title="Permalink to this headline">¶</a></h4>
<p>This module allows you to take full control of the content inside your container,
i.e., the user mentions the binaries/packages required for creation of the
container. The installation of any software, necessary configuration files can all be
mentioned in the <code class="docutils literal notranslate"><span class="pre">%setup</span></code> section of the definition file. This agent is
particularly useful for creating minimal image sizes and is more secure since
the creator is fully aware of what’s inside the container (ideally only the
items required to run your application) and hence reduces the attack surface.</p>
</div>
<div class="section" id="id29">
<h4>Keywords<a class="headerlink" href="#id29" title="Permalink to this headline">¶</a></h4>
<div class="highlight-singularity notranslate"><div class="highlight"><pre><span></span><span class="k">Bootstrap</span>: scratch
</pre></div>
</div>
<p>Since you are building the image from scratch, it does not require and hence
does not support any keywords.</p>
</div>
</div>
</div>
</div>


           </div>
           
          </div>
          <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <a href="cli.html" class="btn btn-neutral float-right" title="Command Line Interface" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
      
      
        <a href="contributing.html" class="btn btn-neutral float-left" title="Contributing" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
      
    </div>
  

  <hr/>

  <div role="contentinfo">
    <p>
        &copy; Copyright 2017-2019, Sylabs Inc

    </p>
  </div>
  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. 

</footer>

        </div>
      </div>

    </section>

  </div>
  


  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script>

  
  
    
   

</body>
</html>